home *** CD-ROM | disk | FTP | other *** search
/ Giga Games 1 / Giga Games.iso / net / go / info / smartgo.def < prev    next >
Encoding:
Text File  |  1993-06-20  |  10.1 KB  |  243 lines
  1.                    DEFINITION OF THE SMART-GO FORMAT
  2.  
  3. From the Dissertation of Anders Kierulf
  4.  
  5. "Smart Game Board:
  6. a Workbench for Game-Playing
  7. Programs, with Go and Othello
  8. as Case Studies"
  9.  
  10. Entered by Greg Hale with permission for distribution. See the many sample 
  11. files from the 'My Go Teacher' series for examples. 
  12.     
  13. ------------
  14.  
  15. A standard file format to exchange machine-readable games, problems,
  16. and opening libraries would save time and work.  That goal may not be
  17. too far away.  A standard for exchanging collections of Othello games
  18. is being worked out by Erik Jensen, Emmanuel Lazard, and Brian Rose in
  19. collaboration with the author.  For Go, a new standard has recently
  20. been proposed [Connelley 89, High 89]; it seems to suffer from a wealth
  21. of features, but any standard for exchanging Go games is welcome, and
  22. will be supported by the Smart Game Board.
  23.  
  24. The current file format is specialized for the needs of the Smart Game
  25. Board.  It is based on an earlier proposal for a standard for Go games
  26. [Kierulf 87b] which was not widely adopted.  The following description
  27. is not a new proposal; it is intended for those who want to read or
  28. white files that are compatible with the Smart Game Board.
  29.  
  30. The game collections (documents) of the Smart Game Board are stored as
  31. text files.  This has the advantage that files can be manipulated with
  32. standard text utilities, and that it's easier to exchange games by
  33. electronic mail.  The disadvantage is that text files are less compact
  34. than binary files.
  35.  
  36. The Smart Game Board stores the game trees of each document, with all
  37. their nodes and properties, and nothing more.  Thus the file format
  38. reflects the regular internal structure of a tree of property lists.
  39. There are no exceptions; if a game needs to store some information on
  40. file with the document, a (game-specific) property must be defined for
  41. that purpose.
  42.  
  43. I will first define the syntax of the game collections, then discuss
  44. syntax and semantic of various properties.
  45.  
  46.  
  47. GAME COLLECTIONS
  48.  
  49. A collection of game sis simply the concatenation of the game trees.
  50. The structure of each tree is indicated by parentheses.  A tree is
  51. written as "(" followed by a sequence of nodes (as long as the tree is
  52. unbranched) and a tree for each son, and terminated by ")".  Each node
  53. is preceded by a separator, and contains a list of zero or more
  54. properties.
  55.  
  56. Thus the main branch of the game is stored first in the file, and
  57. programs can easily read that part (until the first closing
  58. parenthesis) and ignore the rest.
  59.  
  60. The conventions of EBNF are discussed in [Wirth 85].  A quick summary:
  61.  
  62. "..." : terminal symbols
  63. [...] : option: occurs at most once
  64. {...} : repetition: any number of times, including zero
  65. (...) : grouping
  66.   |   : exclusive-or
  67.  
  68. The overall definition of the file format is as follows:
  69.  
  70.         Collection      = {GameTree}.
  71.         GameTree        = "(" Sequence {GameTree} ")".
  72.         Sequence        = Node {Node}.
  73.         Node            = ";" {Property}
  74.  
  75. Any text before the first opening parenthesis is reserved for future
  76. extensions and is ignored when reading a file.  Spaces, tabs, line
  77. breaks and so on can be inserted anywhere between properties and are
  78. also ignored.
  79.  
  80.  
  81. GAME-INDEPENDENT PROPERTIES
  82.  
  83. Each property is identified by one or two capital letters.  The
  84. property value is enclosed in brackets; lists of points or integers are
  85. written as a sequence of property values.  Within text, a closing
  86. bracket is prefixed by a backslash, and a backslash is doubled.  Moves
  87. and points are game-specific and are defined later.
  88.  
  89.         Property        = PropIdent PropValue {PropValue}.
  90.         PropIdent       = UpperCase [UpperCase | Digit].
  91.         PropValue       = "[" [Number | Text | Real | Triple
  92.                                   | Color | Move | Point | ... ] "]"
  93.         Number          = ["+" | "-"] Digit {Digit}.
  94.         Text            = { any character; "\]" = "]", "\\" = "\"}.
  95.         Real            = { Number ["." {Digit}].
  96.         Triple          = ("1" | "2").
  97.         Color           = ("B" | "W").
  98.  
  99. Move and Point are game-specific and are described later.  The
  100. following properties are understood by all games.  The property type is
  101. given in brackets.
  102.  
  103.         "B" : Black move                [move, game-specific]
  104.         "W" : White move                [move, game-specific]
  105.         "C" : Comment                   [Text]
  106.         "N" : Node Name                 [Text]
  107.  
  108. The purpose of providing both a node name and a comment is to have a
  109. short identifier like "doesn't work" or "Dia. 15" that can be displayed
  110. directly with the properties of the node, even if the comment is turned
  111. off or shown in a separate window.  There is no limit to the length of
  112. texts; programs must be able to ignore the rest of texts that are too
  113. long for them to handle.  Reasonable limits are 32 characters for node
  114. names and at least 2000 characters for comments.
  115.  
  116.         "V" : Node value                [number]
  117.  
  118. Positive values are good for Black, negative values are good for
  119. White.  The interpretation of particular values is game-specific.
  120.  
  121.         "CH": Check mark                [triple]
  122.         "GB": good for black            [triple]
  123.         "GW": good for white            [triple]
  124.         "TE": good move (tesuji)        [triple]
  125.         "BM": bad move                  [triple]
  126.  
  127. The normal value for such properties is one, properties that are
  128. doubled for emphasis have the value two.
  129.  
  130.         "BL": time left for Black       [real]
  131.         "WL": time left for White       [real]
  132.  
  133. All times are given in seconds, or fractions thereof {Hale: these can
  134. be negative, indicating player is playing past time limit set}.
  135.  
  136.         "FG": figure                    [none]
  137.  
  138. The figure property is used to divide a game into different figures for
  139. printing: a new figure starts at the node with a figure property.
  140.  
  141.         "AB": add black stones          [point list, game specific]
  142.         "AW": add white stones          [point list, game specific]
  143.         "AE": add empty stones          [point list, game specific]
  144.         "PL": player to play first      [color]
  145.  
  146. The above properties are used to set up positions in games with only
  147. black and white stones.  The following properties are all part of the
  148. game info:
  149.  
  150.         "GN": game name                 [text]
  151.         "GC": game comment              [text]
  152.         "EV": event (tournament)        [text]
  153.         "RO": round                     [text]
  154.         "DT": date                      [text]
  155.         "PC": place                     [text]
  156.         "PB": black player name         [text]
  157.         "PW": white player name         [text]
  158.         "RE": result, outcome           [text]
  159.         "US": user (who entered game)   [text]
  160.         "TM": time limit per player     [text]
  161.         "SO": source (book, journal...) [text]
  162.  
  163. The format in these game-info strings is free, but to be able to search
  164. for specific games in game collections, it is recommended to adhere to
  165. the following conventions:
  166.  
  167.         - Date is ISO-standard: "YYYY-MM-DD".
  168.         - Result as "0" (zero) for a draw, "B+score" for a black win,
  169.                 and "W+score" for a white win, e.g. "B+2.5", "W+64"
  170.         - Time limit as a number, in minutes.
  171.  
  172. In addition, names, events, and places should be spelled the same im all games.
  173.  
  174. The following properties may only be present at the root node:
  175.  
  176.         "GM": game [number] (Go=1, Othello=2, chess=3, Nine Mens Morris=5)
  177.         "SZ": board size        [number]
  178.         "VW": partial view      [point list, game-specific]
  179.         "BS": black species     [number] (human=0, modem=-1, computer>0)
  180.         "WS": white species     [number]
  181.  
  182. The game number helps the program reject games it cannot handle (this
  183. property was mandatory as long as an application could play different
  184. games).  The view gives two corner points of a rectangular subsection;
  185. an empty list denotes the whole board.  The species denotes the kind of
  186. player (the source of the more input), with different version of
  187. computer algorithms denoted by positive numbers (default algorithm =
  188. 1).
  189.  
  190. Computer algorithms may add the following properties:
  191.  
  192.         "EL": evaluation of computer move       [number]
  193.         "EX": expected next move                [move, game-specific]
  194.  
  195. Some games support markings on the board: selected points,
  196. triangles/crosses, or letters (a sequence of letters is shown on the
  197. points given in the list, starting with "A"):
  198.  
  199.         "SL": selected points                   [point list, game-specific]
  200.         "M" : marked points                     [point list, game-specific]
  201.         "L" : letters on points                 [point list, game-specific]
  202.  
  203.  
  204. GO-SPECIFIC PROPERTIES
  205.  
  206. In my proposal for a standard [Kierul 87b], I intentionally broke with
  207. the tradition of labeling moves (and points) with letters "A"-"T"
  208. (excluding "i") and numbers 1-19.  Two lowercase letters in the range
  209. "a"-"s" were used instead, for reasons of simplicity and compactness.
  210. This was criticized mainly because it was not human-readable, but as
  211. that is not an important feature of this file format, I continue to use
  212. that notation.
  213.  
  214. (Hale: diagram omitted)
  215.  
  216. The first letter designated the column (left to right), the second the
  217. row (top to bottom).  The upper left part of the board is used for
  218. smaller boards, e.g. letters "a"-"m" for 13*13.  (Column before row
  219. follows the principle "horizontal before vertical" used in x-y
  220. coordinate systems.  The upper left corner as origin of the board
  221. corresponds to the way we read, and most modern computers use it as
  222. origin of the screen coordinates to simplify integration of text and
  223. graphics.)  A pass move is written as "tt".
  224.  
  225. The board must be quadratic, no smaller than 2x2, and no larger than
  226. 19x19.
  227.  
  228. Additional game info properties are defined for Go:
  229.  
  230.         "BR": Black's rank              [text]
  231.         "WR": White's rank              [text]
  232.         "HA": handicap                  [number]
  233.         "KM": komi                      [real]
  234.  
  235. Sets of board points can be marked as territory, as secure stones, or
  236. just as a region of the board (e.g. to designate eye space):
  237.  
  238.         "TB": Black's territory         [point list]
  239.         "TW": White's territory         [point list]
  240.         "SC": secure stones             [point list]
  241.         "RG": region of the board       [point list]
  242.  
  243.